﻿<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
<title>ASP.NET Boilerplate documentation</title>
<link type="text/css" rel="stylesheet" href="bootstrap.min.css" />
</head>

<body>

<h3>Problems of AJAX operations</h3>
<p>Performing an AJAX call is frequently used by modern applcations. Especially 
in SPAs (Single-Page Applications), it's almost the only way of communicating 
with the server.</p>
<p>An AJAX call consists of some repeating steps:</p>
<p>In client side, basically, javascript code should supply a URL, optionally a 
data and select a method (POST, GET...) to perfom an AJAX call. It must wait and 
handle the return value. There may be an error (network error generally) while 
performing call to the server. There may be some error in server side and server 
may send an failed response with an error message. Client code should handle 
this and optionally notify user (may show an error dialog). If no error and 
server sent a return data, it must also handle it. Also, generally it blocks 
some (or whole) area of the screen and shows a busy indicator until AJAX 
operation complete.</p>
<p>Server code should get the request, perform some server-side code, catch any 
exceptions and return a valid response to the client. In an error situation, it 
may optionally send an error message to the client. In success, it may send a 
return data to the client.</p>
<h3>ASP.NET Boilerplate way</h3>
<p>ASP.NET Boilerplate automates some of these steps by wrapping AJAX calls with
<strong>abp.ajax</strong> function. An example ajax call:</p>
<pre lang="js">var newPerson = {
    name: 'Dougles Adams',
    age: 42
};

abp.ajax({
    url: '/People/SavePerson',
    data: JSON.stringify(newPerson)
}).done(function(data) {
    abp.notify.success('created new person with id = ' + data.personId);
});</pre>
<p>abp.ajax gets <strong>options</strong> as an object. You can pass any 
parameter that is valid in jQuery's
<a href="http://api.jquery.com/jQuery.ajax/" target="_blank">$.ajax</a> method. 
There are some <strong>defaults</strong> here: dataType is '<strong>json</strong>', 
type is '<strong>POST</strong>' and contentType is '<strong>application/json</strong>' 
(So, we're calling JSON.stringify to convert javascript object to JSON string 
before sending to the server). You can override 
defaults by passing options to abp.ajax.</p>
<p>abp.ajax returns <strong>
<a href="http://api.jquery.com/deferred.promise/" target="_blank">promise</a></strong>. So, you can write done, fail, then... handlers. In 
this example, we made a simple AJAX request to <strong>PeopleController</strong>'s
<strong>SavePerson</strong> action. In the <strong>done </strong>handler, we got the database
<strong>id</strong> for the new created person and showing a success notification (See
<a href="/Pages/Documents/Javascript-API/Notification">notification API</a>). Let's see the <strong>MVC controller</strong> for this AJAX call:</p>
<pre lang="cs">public class PeopleController : AbpController
{
    [HttpPost]
    public JsonResult SavePerson(SavePersonModel person)
    {
        //TODO: save new person to database and return new person's id
        return Json(new {PersonId = 42});
    }
}</pre>
<p><strong>SavePersonModel</strong> contains Name and Age properties as you guess. 
SavePerson is marked with <strong>HttpPost</strong> since abp.ajax's default 
method is POST. I simplified method implemtation by returning an anonymous 
object.</p>
<p>This seams straightforward, but there are some important things behind the 
scenes that is handled by ASP.NET Boilerplate. Let's dive into details...</p>
<h4>AJAX return messages</h4>
<p>Even we directly return an object with PersonId = 2, ASP.NET 
Boilerplate wraps it by an <strong>MvcAjaxResponse</strong> object. Actual 
AJAX response is something like that:</p>
<pre lang="cs">{
  "success": true,
  "result": {
    "personId": 42
  },
  "error": null,
  "targetUrl": null,
  "unAuthorizedRequest": false
}</pre>
<p>Here, all properties are camelCase (since it's conventional in javascript 
world) even they are PascalCase in the server code. Let's explain all fields:</p>
<ul>
	<li><strong>success</strong>: A boolean value (true or false) that indicates 
	success status of the operation. If this is true, abp.ajax resolves the 
	promise and calls the <strong>done</strong> handler. If it's false (if there 
	is an exception thrown in method call), it calls
	<strong>fail</strong> handler and shows the <strong>error</strong> message 
	using <a href="/Pages/Documents/Javascript-API/Message">abp.message.error</a> 
	function.</li>
	<li><strong>result</strong>: Actual return value of the controller action. 
	It's valid if success is true and server sent a return value.</li>
	<li><strong>error</strong>: If success is false, this field is an object 
	that contains <strong>message</strong> and <strong>details</strong> fields.</li>
	<li><strong>targetUrl</strong>: This provides a possibility to the server to
	<strong>redirect</strong> client to another url if needed.</li>
	<li><strong>unAuthorizedRequest</strong>: This provides a possibility to the 
	server to inform client that this operation is not authorized or user is not 
	authenticated. abp.ajax <strong>reloads</strong> current page if this is 
	true.</li>
</ul>
<p>Converting your return value to a wrapped AJAX response is possible by 
deriving from <strong>AbpController</strong> class. It's recognized and evaluated by <strong>
abp.ajax</strong> function. So, they work as pairs. Your done handler in 
abp.ajax gets the actual return value of the controller (An object with personId 
property) if there is no error.</p>
<p>Same mechanism exists in <strong>Web API controllers</strong> also when you 
derive from <strong>AbpApiController</strong> class.</p>
<h4>Handling errors</h4>
<p>As described above, ASP.NET Boilerplate handles all exceptions in server and 
returns an object with an error message like that:</p>
<pre lang="js">{
  "targetUrl": null,
  "result": null,
  "success": false,
  "error": {
    "message": "An internal error occured during your request!",
    "details": "<span lang="tr">...</span>"
  },
  "unAuthorizedRequest": false
}</pre>
<p>As you see, <strong>success is false</strong> and <strong>result is null</strong>. 
abp.ajax handles this object and shows an error message to the user using
<a href="/Pages/Documents/Javascript-API/Message">abp.message.error</a> 
function. If your server side code throws an exception type of 
<strong>UserFriendlyException</strong>, it directly shows exception's message to the user. 
Otherwise, it hides the actual error (writes error to logs) and shows a standard 
''An internal error occured..." message to the user. All these are automatically 
done by ASP.NET Boilerplate.</p>

<h4>Dynamic Web API Layer</h4>
<p>While ASP.NET Boilerplate provides a mechanism to make easy AJAX calls, in a 
real world application it's typical to write a javascript function for every 
AJAX call. For example:</p>
<pre lang="js">//Create a function to abstract AJAX call
var savePerson = function(person) {
    return abp.ajax({
        url: '/People/SavePerson',
        data: JSON.stringify(person)
    });
};

//Create a new person
var newPerson = {
    name: 'Dougles Adams',
    age: 42
};

//Save the person
savePerson(newPerson).done(function(data) {
    abp.notify.success('created new person with id = ' + data.personId);
});</pre>
<p>This is a good practice but time-consuming and tedious to write a function 
for every ajax call. ASP.NET provides a mechanism to automatically generate 
these type of functions for <a href="/Pages/Documents/Application-Services">
application service</a> methods. Read the
<a href="/Pages/Documents/Dynamic-Web-API">dynamic web api</a> layer 
documentation.</p>

</body>

</html>
